Release 10.1A: OpenEdge Development:
Progress 4GL Reference

DEFINE FRAME statement

Defines and creates a frame or dialog box that can be used within a procedure or shared among several procedures.

Syntax

DEFINE [ [ NEW ] SHARED ] [ PRIVATE ] FRAME frame [ form-item ... ] [{ HEADER | BACKGROUND } head-item ... ] { [ frame-phrase ] }

DEFINE [ [ NEW ] SHARED ] FRAME frame record [ EXCEPT field ... ] { [ frame-phrase ] }

NEW SHARED FRAME frame

Defines and identifies a frame to be shared by a procedure called directly or indirectly by the current procedure. The called procedure must name the same frame in a DEFINE SHARED FRAME statement.

SHARED FRAME frame

Defines and identifies a frame that was created by another procedure that used the DEFINE NEW SHARED FRAME statement. When you use the DEFINE SHARED FRAME statement, you cannot name any fields or variables in that frame that are not already named in the frame described by the DEFINE NEW SHARED FRAME statement.

[ PRIVATE ] FRAME frame

Defines and identifies a frame widget as a data member for a class, and optionally specifies an access mode for that data member. Do not specify the access mode when defining a frame widget for a method within a class.

PRIVATE data members can be accessed only by the defining class. The default access mode is PRIVATE.

Note: This option is applicable only when defining a data member for a class in a class definition (.cls) file.

FRAME frame

Identifies the name of the frame widget you are defining. You can define the frame widget in a procedure or a method within a class.

form-item

Specifies a field-level widget or value to display in the frame, or a SPACE or SKIP directive. The data specified by all form items is owned by a single field group, duplicated for each data iteration in the frame.

This is the syntax for form-item:

{ field [ format-phrase ] | constant [ at-phrase | { TO n } ] [ BGCOLOR expression ] [ DCOLOR expression ] [ FGCOLOR expression ] [ FONT expression ] [ PFCOLOR expression ] [ VIEW-AS TEXT ]        [ WIDGET-ID id-number ] | SPACE [ ( n ) ] | SKIP [ ( n ) ] }

field

Specifies a field-level widget to be displayed in the frame. This value cannot be an expression or a frame. To specify a child frame, you must first define the parent and child frames, and then assign the FRAME attribute of the child frame to the widget handle of the parent frame. The child frame is assigned to the same field group as other form items.

format-phrase

Specifies one or more frame attributes for a field or variable. For more information on format-phrase, see the Format phrase reference entry.

constant

A constant value.

at-phrase

Specifies the location of a value within the frame. The AT phrase does not left justify the data; it simply indicates the placement of the data area. This is the syntax for at-phrase:

AT { COLUMN column | COLUMN-OF reference-point } { ROW row | ROW-OF reference-point } [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]

AT { X x | X-OF reference-point } { Y y | Y-OF reference-point } [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ]

AT n

For more information, see the AT phrase reference entry.

TO n

The number (n) of the column where you want the right edge of the value. The TO option does not right justify the data; it simply indicates the placement of the data area.

BGCOLOR expression

Specifies the background color of the form item in graphical interfaces. This option is ignored in character interfaces.

DCOLOR expression

Specifies the display color of the form item in character interfaces. This option is ignored in graphical interfaces.

FGCOLOR expression

Specifies the foreground color of the form item in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies the font of the form item.

PFCOLOR expression

Specifies the prompt color of the form item in character interfaces. This option is ignored in graphical interfaces.

VIEW-AS TEXT

Specifies that the form item displays as a TEXT widget rather than as a FILL-IN.

WIDGET-ID id-number

Specifies a widget ID for a field-level widget or value to display in a frame. The value of id-number must be an expression that evaluates to an even integer value between 2 and 65534, inclusive, and must be unique across all widget IDs in the window or dialog box.

If you specify an invalid ID, the compiler displays an error message. This option is supported in graphical interfaces only, and only in Windows.

SPACE ( n )

Identifies the number (n) of blank spaces to insert after the expression displays. The n can be 0. If the number of spaces you specify is more than the spaces left on the current line of the frame, Progress starts a new line and discards extra spaces. If you do not use this option or you do not use n, Progress inserts one space between items in the frame.

SKIP ( n )

Identifies the number (n) of blank lines to insert after the expression is displayed. The number of blank lines can be can be 0. If you do not use this option, Progress does not skip a line between expressions unless the expressions do not fit on one line. If you use the SKIP option but do not specify n, or if n is 0, Progress starts a new line unless it is already at the beginning of a new line.

record

Represents the name of the record you want to display. Naming a record is shorthand for listing each field individually, as a form item.

EXCEPT field . . .

Tells Progress to display all the fields in the frame except those fields listed in the EXCEPT phrase.

HEADER

Tells Progress to place the following items in a header section at the top of the frame in a separate field group from all other data. In addition to fields, variables, and constants, the frame header can contain expressions, images, and rectangles. Progress reevaluates these expressions each time it displays the frame.

When you use the HEADER option, Progress disregards OpenEdge Data Dictionary field labels for fields you name in the DEFINE FRAME statement. Use character strings to specify labels on fields you name in the frame header.

BACKGROUND

Specifies that any following frame items are displayed in the frame background, behind the data and header in a separate field group. Typically, this option is used to display images or rectangles behind the data.

head-item

A description of a value displayed in the frame header or background, or a SPACE or SKIP directive. Following is the syntax head-item:

{ expression [ format-phrase ] | constant [ at-phrase | { TO n } ] [ BGCOLOR expression ] [ DCOLOR expression ] [ FGCOLOR expression ] [ FONT expression ] [ VIEW-AS TEXT ]         [ WIDGET-ID id-number ] | SPACE [ ( n ) ] | SKIP [ ( n ) ] }

This is exactly the same as the syntax for a form-item, except that a head-item can be an expression and does not include the PFCOLOR option. If you use an expression in a HEADER or BACKGROUND phrase, the expression is evaluated each time the frame is viewed. If you give the PAGE-TOP or PAGE-BOTTOM option for the frame, the expression is evaluated for each page. This lets you include a reference to the PAGE-NUMBER function in the frame header.

frame-phrase

Specifies additional options for the frame, including the VIEW-AS DIALOG-BOX option to define the frame as a dialog box. For more information on frame and dialog box options, see the Frame phrase reference entry.

Examples

The following example, r-deffrm.p, uses the DEFINE FRAME statement to set up the format of a frame. It then scopes that frame to a FOR EACH block.

r-deffrm.p

DEFINE VARIABLE bal-avail LIKE customer.balance COLUMN-LABEL "Available!Credit" NO-UNDO. DEFINE FRAME cust-bal customer.cust-num customer.name FORMAT "X(20)" customer.credit-limit LABEL "Limit" customer.balance bal-avail WITH CENTERED ROW 3 TITLE "Available Customer Credit" USE-TEXT. FOR EACH customer NO-LOCK WITH FRAME cust-bal: DISPLAY customer.cust-num customer.name customer.credit-limit customer.balance customer.credit-limit - customer.balance @ bal-avail. END.

The following example defines three frames. The cust-info frame is scoped to the trigger for the b_next button where it is first referenced. Similarly, the cust-dtl frame is scoped to the b_dtl trigger. The butt-frame frame is scoped to the outer procedure block.

r-dffrm1.p

DEFINE BUTTON b_dtl LABEL "Detail". DEFINE BUTTON b_next LABEL "Next". DEFINE BUTTON b_quit LABEL "Quit" AUTO-ENDKEY. DEFINE FRAME cust-info customer.cust-num customer.name FORMAT "X(20)" customer.phone WITH CENTERED ROW 4. DEFINE FRAME cust-dtl customer except customer.cust-num customer.name customer.phone WITH CENTERED SIDE-LABELS ROW 9. DEFINE FRAME butt-frame b_dtl b_next b_quit WITH ROW 1. ON CHOOSE OF b_dtl DISPLAY customer except customer.cust-num customer.name customer.phone WITH FRAME cust-dtl. ON CHOOSE OF b_next DO: HIDE FRAME cust-dtl. FIND NEXT customer NO-LOCK NO-ERROR. IF NOT AVAILABLE customer THEN FIND LAST customer NO-LOCK. DISPLAY customer.cust-num customer.name customer.phone WITH FRAME cust-info. END. ENABLE ALL WITH FRAME butt-frame. APPLY "CHOOSE" TO b_next IN FRAME butt-frame. WAIT-FOR CHOOSE OF b_quit.

The following example uses a set of thin rectangles as lines to create graphic columns within a frame background:

r-bkgrnd.p

DEFINE VARIABLE item-tot AS DECIMAL LABEL "Value" NO-UNDO. DEFINE RECTANGLE vline1 SIZE .4 BY 5 EDGE-PIXELS 2. DEFINE RECTANGLE vline2 LIKE vline1. DEFINE RECTANGLE vline3 LIKE vline1. DEFINE RECTANGLE vline4 LIKE vline1. DEFINE RECTANGLE vline5 LIKE vline1. DEFINE RECTANGLE vline6 LIKE vline1. DEFINE RECTANGLE hline SIZE 78 BY .1 EDGE-PIXELS 2. DEFINE FRAME item-info item.item-num item.item-name item.on-hand item.re-order item.on-order item.price item-tot BACKGROUND skip(1) hline vline1 AT 9 vline2 AT 25 vline3 AT 33 vline4 AT 42 vline5 AT 51 vline6 AT 65 WITH TITLE "Inventory Current Value" CENTERED USE-TEXT 5 DOWN. FOR EACH item NO-LOCK WITH FRAME item-info: DISPLAY item.item-num item.item-name item.on-hand item.re-order item.on-order item.price item.on-hand * item.price @ item-tot.

The following procedure defines the shared frame cust-frame. It also defines a shared variable and a shared buffer. For each customer whose customer number is less than 20, the procedure displays customer information in the cust-frame. The format for the cust-frame is defined in the r-shrfrm.i include file.

r-shrfrm.p

DEFINE NEW SHARED FRAME cust-frame. DEFINE NEW SHARED VARIABLE csz AS CHARACTER FORMAT "x(29)". DEFINE NEW SHARED BUFFER xcust FOR customer. FOR EACH xcust WHERE cust-num <=20: {r-shrfrm.i} /* include file for layout of shared frame */ DISPLAY name phone address sales-rep city + ", " + st + " " + postal-code @ csz credit-limit WITH FRAME cust-frame. RUN r-updord.p. /* External procedure to update customer’s orders */ END.

r-shrfrm.i

FORM xcust.name COLON 10 xcust.phone COLON 55 xcust.address COLON 1 xcust.sales-rep COLON 55 csz NO-LABEL COLON 10 xcust.credit-limit COLON 55 SKIP(2) order.order-num COLON 10 order.order-date COLON 30 order.ship-date COLON 30 order.promise-date COLON 30 WITH SIDE-LABELS 1 DOWN CENTERED ROW 5 TITLE "Customer/Order Form" FRAME cust-frame.

After the r-shrfrm.p procedure displays the customer information, it calls the r-updord.p procedure.

The r-updord.p procedure defines the variable, frame, and buffer that were originally defined in the r-shrfrm.p procedure. However, in this second reference to the items, the keyword NEW is omitted. The r-updord.p procedure displays, and lets you update, the order information for the customer displayed in the cust-frame. The order information is displayed in the same frame.

r-updord.p

DEFINE SHARED FRAME cust-frame. DEFINE SHARED VARIABLE csz AS CHARACTER FORMAT "x(29)". DEFINE SHARED BUFFER xcust FOR customer. FOR EACH order OF xcust: {r-shrfrm.i } /* include file for layout of shared frame */ DISPLAY order.order-num WITH FRAME cust-frame. UPDATE order.order-date order.ship-date order.promise-date WITH FRAME cust-frame. END.

The following example, r-fof1.p, creates a dialog box to display customer information from a query. The dialog box contains three child frames to display customer contact information (FRAME cont-fr), customer account information (FRAME acct-fr), and control buttons for moving through the query results list (FRAME ctrl-fr).

r-fof1.p

DEFINE QUERY custq FOR customer. DEFINE BUTTON bprev LABEL "<". DEFINE BUTTON bnext LABEL ">". DEFINE FRAME cust-fr SKIP(.5) SPACE(8) customer.name customer.cust-num customer.sales-rep customer.comments AT COLUMN 6 ROW 13.5 WITH SIDE-LABELS TITLE "Customer Data" SIZE 80 BY 15 VIEW-AS DIALOG-BOX. DEFINE FRAME cont-fr SKIP(.5) customer.address COLON 17 SKIP customer.address2 COLON 17 SKIP customer.city COLON 17 SKIP customer.state COLON 17 SKIP customer.postal-code COLON 17 SKIP customer.country COLON 17 SKIP customer.contact COLON 17 SKIP customer.phone COLON 17 WITH SIDE-LABELS TITLE "Contact Informaion" SIZE 40 BY 10 AT COLUMN 1 ROW 3.

DEFINE FRAME ctrl-fr SKIP(.12) SPACE(4) bprev bnext WITH TITLE "PREVIOUS/NEXT" SIZE 15 BY 2 AT COLUMN 53 ROW 10.5. DEFINE FRAME acct-fr SKIP(.5) customer.balance COLON 15 SKIP customer.credit-limit COLON 15 SKIP customer.discount COLON 15 SKIP customer.terms COLON 15 WITH SIDE-LABELS TITLE "Account Information" SIZE 38.85 BY 6 AT COLUMN 41 ROW 3. ON CHOOSE OF bnext DO: GET NEXT custq. IF NOT AVAILABLE customer THEN GET FIRST custq. RUN display-proc IN THIS-PROCEDURE. END. ON CHOOSE OF bprev DO: GET PREV custq. IF NOT AVAILABLE customer THEN GET LAST custq. RUN display-proc IN THIS-PROCEDURE. END. FRAME cont-fr:FRAME = FRAME cust-fr:HANDLE. FRAME acct-fr:FRAME = FRAME cust-fr:HANDLE. FRAME ctrl-fr:FRAME = FRAME cust-fr:HANDLE. OPEN QUERY custq PRESELECT EACH customer BY customer.name. GET FIRST custq. RUN display-proc IN THIS-PROCEDURE. ENABLE ALL WITH FRAME ctrl-fr. WAIT-FOR WINDOW-CLOSE OF FRAME cust-fr. PROCEDURE display-proc: DISPLAY customer.name customer.cust-num customer.sales-rep customer.comments WITH FRAME cust-fr. DISPLAY customer.address customer.address2 customer.city customer.state customer.postal-code customer.country customer.contact customer.phone WITH FRAME cont-fr. DISPLAY customer.balance customer.credit-limit customer.discount customer.terms WITH FRAME acct-fr. END.

Notes

You cannot define a SHARED or NEW SHARED frame widget in a persistent procedure. If you do, Progress raises ERROR on the RUN statement that creates the procedure.
You cannot define a SHARED or NEW SHARED frame widget in a class definition (.cls) file. If you do, Progress generates a compilation error.
If you do not specify the font for a frame, Progress uses the system default font, not the font of the window. This is because Progress determines the frame layout at compile time when the window’s fonts (known at runtime) are not yet available.
You can use just one DEFINE FRAME statement per frame in a procedure.
If you name variables or parent child frames to a shared frame, Progress does not automatically make those variables and child frames shared. If you want to share the variables and child frames among procedures, you must define each variable and frame using the SHARED option in all the sharing procedures.
Progress scopes a newly defined frame to the block that first references the frame. (The DEFINE FRAME statement does not count as a reference.) Progress scopes a shared frame outside of the called procedure.
The frame-phrase options specified in a DEFINE NEW SHARED FRAME statement are carried over to all corresponding DEFINE SHARED FRAME statements and cannot be overridden.
You can use different field-level help and validation in new shared, and shared frames.
You must define a shared frame before referencing that frame in a procedure.
All frame fields and Frame phrase options in a shared frame must first be defined in the initial DEFINE NEW SHARED FRAME statement or an additional FORM statement in the same procedure. Procedures that share this frame only have to define fields that correspond to the fields in the initial definition plus any specified ACCUM option. Other Frame phrase options for the SHARED frames are allowed, but are ignored except for the ACCUM option. This allows you to make use of the same FORM statement in an include file for both the NEW SHARED and matching SHARED frames. See the FORM statement reference entry for more information.
If you use an Aggregate phrase to accumulate a value within a shared frame, you must also use the ACCUM option in each procedure that uses the shared frame.
If you define a frame to use as a DDE frame, you must realize the frame (display it) before using it as a conversation end-point. If you want the DDE frame to remain invisible during its use in a DDE conversation, set its HIDDEN attribute to TRUE after realizing the frame. For information on DDE frames, see OpenEdge Development: Programming Interfaces .
If you have enabled application-defined widget IDs in your OpenEdge GUI application, by specifying the Use Widget ID (–usewidgetid) startup parameter, then Progress uses the value specified in the WIDGET-ID option to set the WIDGET-ID attribute for this widget when it creates the widget at runtime, instead of using the widget ID it normally generates by default. If you have not enabled application-defined widget IDs, then Progress ignores this option setting at runtime.

For more information about the WIDGET-ID attribute, see its reference entry in the "Attributes and Methods Reference" section. For more information about the Use Widget ID (–usewidgetid) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference .

See also

DEFINE BUFFER statement, DEFINE VARIABLE statement, FORM statement, Frame phrase, RUN statement